Power CD

home *** CD-ROM | disk | FTP | other *** search

/ Power CD / Power CD ATARI-Rechner Lieben.iso / SPEZIAL / GEMVIEW / UTILITY / GEM_VIEW.101 / VIEW_101.ENG < prev

Wrap

Text File | 1993-09-14 | 14.8 KB | 431 lines

view.txt V1.01, 19.08.1993 The 'View'-protocol ======================= This is now version 1.01 of view.txt. Julian Reschke had the brilliant idea, that a 'View' environment variable would be much better than the cookie, we used before. The aim of the 'View'-protocol is that all (GEM-)applications can easily display files using a 'viewer' and needn't implement view-functions for various formats themselves. As there are already several view-applications, as GEM-View (from Dieter Fiebelkorn) or 1st-View/1st-Guide (from Guido Vollbeding), some applications already have options to use these programs (if installed as an accessory) to view files. This is why Dieter and I have developed the 'View'-protocol, that there is an uniform interface to the different viewers, so every application is able to use installed view-accessories, even if it doesn't know and support it explicitly. This version of the 'View'-protocol is experimentally implemented in GEM-View and ShowImage (my very own viewer). ALL PROGRAMMERS ARE STRONGLY EXPECTED TO USE AND EXPERIMENT WITH THIS PROTOCOL! So we hope that sometime it becomes a standard for viewers and programs that use it. I would *REALLY* like to get any kind of reaction, that I know, if someone else uses this protocol and it should be developed further. So please contact me: Peter Seitz, Robert-Koch-Str.6, 63225 Langen, GERMANY E-Mail (Internet): seitz@rbg.informatik.th-darmstadt.de The 'View'-protocol is based on parts of the XAcc-protocol, so one should get a copy of it's documentation (file xacc_mt.txt). This protocol should be quite easy to implement by both the writers of viewers and of all other applications and should be of a big advantage for the user, as he can use his favourite viewer with all applications. Peter In the following, 'viewer' refers to the accessory or application that is used to display the file(s); 'application' means always a program, that wants to use the 'viewer'. 1. WHO is the viewer??? ======================= * First the application should check, if there is a viewer, the user prefers. Therefore it should see, if there is a) an environment variable named 'View' (the case is significant!). b) a cookie named 'View' (the case is here significant, too). c) the 'SHSHOW' environmenr variable (which is also used by the MTOS' desktop). The value of each one of these variables is a pointer to the full pathname of the viewer. Using appl_find() one can see, if one of them is already loaded (as an ACC or, with a multi-tasking-system, also as an APP). To use appl_find, the path and the extension have to be removed from the name, and the name has to be filled up with spaces to 8 characters - otherwise appl_find() won't find anything at all... It should be noted, that appl_find is case sensitive - so normally the value MUST be all upper case. It wouldn't be wise to convert the name to upper case, as case sensitive file systems may be used (eg under MiNT). If the viewer has not yet sent it's XAcc-identification (ACC_ID- message), the application does this now. This may be the case, if the main-application doesn't support the XAcc-protocol. * If no viewer could be found, the application should check all APPs/ACCs that have sent their XAcc-identification: If the extended name (introduced in version 2 of the XAcc- protocol) contains a string of the form '2View' (this is the application type 'viewer') or 'NView' (the generic type 'viewer' - whatever this means), this is a program that supports the 'View'-protocol and may be used as a viewer. Please notice, that the case of 'View' here is significant, too. * If the application really can't find a viewer, it can at last try to load the viewer itself, if one of the variables / the cookie was found, using the full pathname (given as the value of the variable / cookie). If the 'View' variable / cookie is used, the viewer may be started as an ACC as well; this is possible if Chameleon or MTOS is present. As a consequence the viewer given in the 'View' variable / cookie *MUST* be able to run both as an APP and ACC! If the viewer can't be used as an ACC, the SHSHOW variable have to be used instead. Normally, one should use one of the enironment variables 'View' or 'SHSHOW'. These should be placed in the desktop's environment, as all applications started by the desktop will inherit its environment. This can be done by special programms or if one uses MiNT, it is much easier: just place a line like setenv View C:\GEM_VIEW\GEMVIEW.APP and/or setenv SHSHOW C:\GEM_VIEW\GEMSHOW.PRG in your mint.cnf file. The cookie should normally not be used anymore. 2. WHAT kind of files can be displayed? ======================================= The (XAcc-)extended name of the viewer should contain an entry of the form 'X.ext' for every supported file-formats, where 'ext' may be one of the following: X.ART - Art-Director X.ASC - prargraphs end with CR, lines may end with LF X.B&W - Imagelab Images X.BLK - GFA-Bit-Block (3 words header: width-1 / height-1 / planes) X.BMP - OS/2 Bitmap, MS-Window Bitmaps X.CFN - Calamus Font X.CRG - Calamus Raster X.CTX - Calamus Text X.CVG - Calamus Vektor X.DOC - 1stWord Docs X.DOO - Doodle Mono X.ESM - Enhanced Simplex X.FNT - GDOS - Fonts (and nothing else!!) X.GEM - GEM-Metafile X.GIF - GIF Images X.GVW - Used by GEM-View internally and should *NOT* be in this list!!! X.HEX - Hex-Dump, this means that the viewer may show dumps. X.IFF - IFF-File in general! X.IFF.ILBM - IFF InterLeavedBitMaps. X.IFF.type - other IFF-file types. X.IMC - Signum!2 Images X.IMG - GEM-Images, XIMG X.JPG - JPEG Images X.MAC - MacPaint Images X.NEO - Neochrome Images X.OUT - The GEM 'OUT'-file (see v_alpha_text) X.PAC - STAD Images X.PC[123] - Degas compressed Images X.PCX - PC Paintbrush X.P[BGP]M - Portable Bit Map X.PIC - Screen-Dump (the current resolution) X.PI[123] - Degas uncompressed Images X.RLE - MS-Window Bitmaps X.RSC - GEM Resource Files X.SNP - Becker Snap Shot (3 words header: width/height/planes) X.SP[CU] - Spectrum 512 X.SUN - Sun Rasterfiles X.TGA - Targa Images X.TIF - TIFF Images X.TN[123Y] - Tiny Images X.TXT - ASCII-Text (lines end with CR/LF, it would be nice, if a single LF (unix) or single CR (Mac) would be accepted as a line end, too.) X.XBM - X Bitmap File Note: [abc] means one of the characters 'a', 'b' or 'c' and not the string '[abc]'. All other entries starting with 'X.' are reserved for future versions!! If one want to add other formats, please contact me! It would be wise, if the entries are unique. I recommend the support of X.IMG, X.GEM and X.OUT, as these are the standard formats for GEM-data-exchange! It should be noted, that all the file formats listed here, could be a hint which formats are understood, if the Drag & Drop - protocol is supported - at least the extensions used there should *really* be the same (well, it would be nice...). 3. HOW can I tell the viewer (what is to be shown)? =================================================== * Because of the XAcc2-protocol the application knows, which message-groups are supported and these messages may be used, if the application has the data already in memory (and not within a file). * Use the VIEW_xxx-messages, discussed in (5) below. With these messages the application has the best control of what's happening. These messages may be used, "if and *ONLY* if" the strings '2View' or 'NView' are found in the viewer's extended XAcc-name, but this should be normaly the case. This may be a problem, if the viewer has been started by the application. In this case I would suggest to try to send the messages and see what's happening - if the viewer doesn't support them no reaction is given (as unknown messages should be ignored!), otherwise the viewer will send a response. * The viewer is *strongly* suggested to support the VA_START- message! Of cause this has to be tested in its protostatus (if possible, see above). * There is NO explicit support of the Drag & Drop - protocol, as this is MiNT-specific, but programs running under MiNT should understand this protocol! * All other protocols of cause may be used to inform the viewer as well, if they give the possibility to check, if they are supported. PLEASE keep in mind, that pointers to strings in messages have to point to global-readable memory (if running in an environment with memory protection)! 4. WHAT does the viewer do? =========================== * On startup the viewer should check its parameters, and load all files given there. He should look for the ARGV-environment- variable, too. * The messages of the XAcc-protocol are answered as usual (with ACC_ACK). By the way: To send data using the XAcc-messages, I would suggest Alt-X as key-combination. * Receiving VA_START the viewer itself has to find out the file's type and if he is able to display it. No reply is given reporting about success or failure! (If reply is needed, use VIEW_FILE!) 5. The VIEW_xxx-messages ======================== This is now the description of the 'View'-protocol's own messages. In difference to VA_START and XAcc one has more possibilities to control, what happens with the viewed file. Please remember, that these messages may be used, "if and *ONLY* if" the strings '2View' or 'NView' are found in the viewer's extended XAcc-name, as mentioned above. In general there are four messages: VIEW_FILE, which may be sent to the viewer, and VIEW_FAILED, VIEW_OPEN and VIEW_CLOSED that are used to inform the application of what has happened to its file. The viewer is expected to answer *EVERY* VIEW_FILE-message he recieves, at least with a VIEW_FAILED(VIEWERR_ERROR) (see below!). However, if the viewer doesn't answer and the application needs one, it should not hang (of cause :-), but use a timeout (about 10 seconds should be enough). It is possible, that the viewer sends some other messages (eg AV_ACCWINDOPEN) before answering the VIEW_FILE-message! a) view a file The 'VIEW_FILE' message is used by the application to inform the viewer, that a file is to be displayed. msg[0] = VIEW_FILE msg[3/4] = filename // must be global-readable (MiNT's memory protection)! msg[5/6] = 0 // reserved! msg[7] = 0 // zero = new file, see below! This message is (always!) answered by the viewer: - if the file couldn't be displayed with VIEW_FAILED: retmsg[0] = VIEW_FAILED retmsg[3/4] = msg[3/4] // filename (same pointer!) retmsg[5] = errcode // see below retmsg[6] = 0 // reserved! retmsg[7] = msg[7] // 0 or >wid< The >errcode< may be a GEMDOS-error-code (< 0) or one of the following: VIEWERR_ERROR - unspecified error VIEWERR_SIZE - wrong size, eg too big VIEWERR_COLOR - unsupported resolution/color VIEWERR_WID - wrong >wid< (see below) It is expected that the viewer informs the users about the error (ie print an message/alertbox), as it knows better what was wrong. - if the file has been displayed, but NO further communication is possible, the viewer sends VIEW_OPEN retmsg[0] = VIEW_OPEN retmsg[3/4] = msg[3/4] // filename retmsg[5] = viewprot_version // currently 0 retmsg[6] = 0 // reserved! retmsg[7] = 0 // 0 = no further communication! - if the file has been displayed AND further communication is possible, the viewer sends VIEW_OPEN retmsg[0] = VIEW_OPEN retmsg[3/4] = msg[3/4] // filename retmsg[5] = viewprot_version // currently 0 retmsg[6] = 0 // reserved! retmsg[7] = wid // not zero! The >wid< refers to the AES' window-id of the window the file is displayed in. This seems to be a unique number representing the file, which is used in the further communication as an identifier. The currently defined >viewprot_version< is 0. b) further communication Once a file is displayed (in a window) and the viewer has returned a non-zero wid in msg[7], both the application and the viewer may send each other messages refering to this file / window. msg[7] will ALWAYS contain the (non-zero) wid as an identifier! As this is (supposed to be) unique, msg[3/4] should NOT be regarded to identify the file (if msg[7] is not zero), as msg[3/4] may be changed. If the viewer receives a wrong wid, he replies by sending a VIEW_FAILED-message: retmsg[0] = VIEW_FAILED retmsg[3/4] = msg[3/4] retmsg[5] = VIEWERR_WID retmsg[6] = 0 retmsg[7] = msg[7] // the wrong wid The application receiving this message must NOT use this wid again, as it might have happened, that the viewer missed to send VIEW_CLOSED(wid). The application now has the following possibilities to control the window: * The window should be closed (and the file's memory freed): msg[0] = VIEW_FILE msg[3/4] = NULL // remove file msg[5/6] = 0 msg[7] = wid // makes only sense, if not zero! * If the application gets somehow to know, that the displayed file has changed (or another file should be displayed in the same window): msg[0] = VIEW_FILE msg[3/4] = filename // may be different msg[5/6] = 0 msg[7] = wid // the window's id On the other side, the viewer should inform the application of what's happening to its file: * If the window is closed (eg the user closed it or the viewer received AC_CLOSE or VIEW_FILE(NULL, wid)): msg[0] = VIEW_CLOSED msg[3/4] = filename // may be NULL and should be ignored! msg[5/6] = 0 msg[7] = wid The >filename< should be the one from the VIEW_FILE- message, otherwise it may be NULL, as no new global memory should to be allocated. If the window was closed due to an error, VIEW_FAILED may be sent instead: msg[0] = VIEW_FAILED msg[3/4] = filename // may be NULL and should be ignored! msg[5] = errcode // see above msg[6] = 0 msg[7] = wid If the viewer has not the possibility to store the application's ap_id, he /may/ not inform the apllication, if the window wasn't closed as a reaction to a application's message. ==> This is much easier to implement but may lead to unexpected results. Please tell me your experiences! 6. The messages'IDs =================== At least the defines for the messages' ids: #define VIEW_FILE 0x5600 #define VIEW_FAILED 0x5601 #define VIEW_OPEN 0x5602 #define VIEW_CLOSED 0x5603 #define VIEWERR_ERROR 0 #define VIEWERR_SIZE 1 #define VIEWERR_COLOR 2 #define VIEWERR_WID 3 // 0x56xx - 'V' as in 'View' !!! All other message-ids from 0x5600 to 0x56FF are reserved for future extensions of the 'View'-protocol!